Diplomatic adder example + basic mdoc infrastructure #2615
Conversation
docs/src/diplomacy/adder_tutorial.md
Outdated
| `SourceNode`s have only outward pointing edges. | ||
|
|
||
| For our `AdderDriverNode`, `widths` of type `Seq[DownwardParam]` represents | ||
| the outputs of this node. We are using a `Seq` here because each node will send |
There was a problem hiding this comment.
"the outputs of this node" => "the output wires of this node's module?"
There was a problem hiding this comment.
I feel like that could be misleading. Will try "the desired widths for the output wires of the module instantiating this node".
docs/src/diplomacy/adder_tutorial.md
Outdated
| lazy val module = new LazyModuleImp(this) { | ||
| // generate random addends | ||
| val randomAddendA = FibonacciLFSR.maxPeriod(nodeA.out.head._2.width) // notice that we are using negotiated | ||
| val randomAddendB = FibonacciLFSR.maxPeriod(nodeB.out.head._2.width) // parameters here |
There was a problem hiding this comment.
It's a little off that you take head here but then foreach below. I mean, diplomacy should make that assumption a safe one for you, but I'd maybe recommend this instead:
def generateRandomAddend(width: Int) = FibonacciLFSR.maxPeriod(width)
nodeA.out.foreach { case (outputAddend, edgeParam) => outputAddend := generateRandomAddend(edgeParam.width) }
nodeB.out.foreach { case (outputAddend, edgeParam) => outputAddend := generateRandomAddend(edgeParam.width) }
There was a problem hiding this comment.
in your code snippet, wouldn't that generate different addends per node? i.e. nodeA would pass two different random numbers into the adder/checker instead of the same random number.
That's why I called the LFSR once with the head width, not sure if you know of a better way to do it.
|
|
||
| `dFn` maps **incoming downward** parameters into **outgoing downward** parameters. | ||
| Similarly, `uFn` maps **incoming upward** parameters into **outgoing upward** ones. | ||
|
|
There was a problem hiding this comment.
Can you clarify what an "incoming" and an "outgoing" parameter is?
There was a problem hiding this comment.
Added some clarification here: 4dbe86e
Hope that helps!
NOTE: The
docsdirectory right now is set up to just contain the raw documentationsrcfiles. We may want to include thegenerateddocuments in the future, but doing this should also include some sort of check to make sure the generated docs are up-to-date with the source.Related issue: N/A
Type of change: other enhancement (documentation)
Impact: no functional change
Development Phase: implementation
Release Notes
Add documentation directory and functionality to generate documents from markdown using embedded
mdoc. Embeddedmdoccode will compile against the codebase as part of CI checks.